Slot and token management functions
This section describes PKCS#11 slot and token management functions.
C_GetSlotList
This function operates as specified in PKCS#11.
Note however that when multiple devices are installed in a single machine they will appear as a set of consecutive slots. For example, for two devices using their default configuration, 4 slots are visible. The first and third slots are normal user slots, the second and fourth slots are the Admin slots for their respective adapters.
Synopsis
C_GetSlotList(
CK_BBOOL tokenPresent,
CK_SLOT_ID_PTR pSlotList,
CK_ULONG_PTR pulCount
);
Operation in WLD Mode
When ProtectToolkit is configured to operate in WLD mode, this function returns the list of slots specified in the WLD configuration. Specifically:
-
When tokenPresent is FALSE, and pSlotList is NULL_PTR, the value *pulcount is set to hold the number of WLD Slots.
-
When tokenPresent is FALSE, and pSlotList is not NULL_PTR, the value *pulcount is set to hold the number of WLD Slots and pSlotList contains the list of WLD Slots.
-
When tokenPresent is TRUE, and pSlotList is NULL_PTR, the value *pulcount is set to hold the number of WLD Slots that have available HSM Tokens.
-
When tokenPresent is TRUE, and pSlotList is not NULL_PTR, the value *pulcount is set to hold the number of WLD Slots that have available HSM Tokens and pSlotList contains the list of WLD Slots that have available HSM Tokens.
C_GetSlotInfo
This function operates as specified in PKCS#11.
The information returned will vary depending on the ProtectToolkit-C runtime in use as well as the actual slot type, for example, if it is a ProtectToolkit-C user slot or a Smart Card slot.
This information is returned in the CK_SLOT_INFO structure.
- SlotDescription
-
“ProtectServer :xxxx, “Safenet Software Only.” or smart card reader type.*
Where xxxx is the slot serialnumber
- ManufacturerID
-
"SafeNet, Inc.” or smart card reader manufacturer.
- Flags
-
CKF_HW_SLOT (hardware only), CKF_REMOVABLE_DEVICE (smart card slots only).
- HardwareVersion
-
Current hardware revision or 0.0 for software only.
- FirmwareVersion
-
Current firmware version or 0.0 for software only.
Synopsis
C_GetSlotInfo(
CK_SLOT_ID slotID,
CK_SLOT_INFO_PTR pInfo
);
Operation in WLD Mode
When ProtectToolkit is configured to operate in WLD mode, a random slot from the HSM Token List for the provided slot ID is chosen, so as not to overload a particular device and the command is forwarded to that slot. The following WLD specific information is returned in the CK_SLOT_INFO structure:
- SlotDescription
-
The slot description specified for the virtual WLD Slot in environment variables ET_PTKC_WLD_SLOT_n. Refer to WLD system setup.
- Flags
-
The CKF_WLD_SLOT bit is set to indicate that it is a WLD Slot. If there are no HSM Tokens available for the particular slot, then the CKF_TOKEN_PRESENT bit in is set to 0.
Note
This breaks PKCS#11 compliance, as this bit should be set to 0 if and only if CKF_REMOVABLE_DEVICE is set. The CKF_REMOVABLE_DEVICE bit is set only for Smart card Slots in the SafeNet implementation.
C_GetTokenInfo
This function operates as specified in PKCS#11. The information returned will vary depending on the type of slot specified by the slotID parameter. This information is returned in the CK_TOKEN_INFO
structure.
- Label
-
This is the string specified by the user during the C_InitToken command, unless the token is the administration token, in which case the value is:
AdminToken(ssss)
Where ssss is the HSM serial number.
- ManufacturerID
-
"SafeNet, Inc.”
- Model
-
“PSI-E2:PLxxx”
Where xxx is the performance level or smartcard manufacturer.
- SerialNumber
-
“xxxx-xxxx”
Where the first field is the HSM serial number and the second field is a randomly assigned token serial number or the smartcard serial number.
- Flags
-
CKF_RNG (for non-smart card slots only) + CKF_CLOCK_ON_TOKEN (if the module’s clock has been set) + CKF_DUAL_CRYPTO_OPERATIONS + Other flags based on the current state of the slot. CKF_LOGIN_REQUIRED flag is set if the security mode specifies “no public crypto”. Admin slot have CKF_ADMIN_TOKEN and CKF_LOGIN_REQUIRED set.
- ulMaxSessionCount
-
The value of that CKA_MAX_SESSIONS for the associated slot object.
- ulSessionCount
-
Determined at run time - this is the total number of session to this Token by all applications.
- ulMaxRwSessionCount
-
The value of that CKA_MAX_SESSIONS for the associated slot object.
- ulRwSessionCount
-
Determined at run time - this is the number of RW sessions the calling application has to the Token.
- ulMaxPinLen
-
CK_MAX_PIN_LEN = 32.
- UlMinPinLength
-
This is the value specified in the configuration as shown by the CKA_MIN_PIN attribute of the slot object.
- UlTotalPublicMemory
-
Determined at run time.
- ulFreePublicMemory
-
Determined at run time.
- ulTotalPrivateMemory
-
Determined at run time.
- ulFreePrivateMemory
-
Determined at run time.
- hardwareVersion
-
‘G’.0 (or later)
- FirmwareVersion
-
1.0 (or later)
- UtcTime
-
Current time is returned if the modules clock has been set (else ASCII zeros are returned).
Synopsis
C_GetTokenInfo(
CK_SLOT_ID slotID,
CK_TOKEN_INFO_PTR pInfo
);
Operation in WLD Mode
When ProtectToolkit is configured to operate in WLD mode, a random slot from the HSM Token List for the provided slot ID is chosen, so as not to overload a particular device and the command is forwarded to that slot. The following WLD specific information is returned in the CK_TOKEN_INFO structure:
- SerialNumber
-
The serial number specified for the virtual WLD Slot in environment variables ET_PTKC_WLD_SLOT_n. Refer to WLD System Setup.
- Flags
-
The CKF_WLD_TOKEN bit is set to indicate that it is a WLD Token.
C_WaitForSlotEvent
This function operates as specified in PKCS#11 except:
The library cannot block while waiting for an event therefore the CKF_DONT_BLOCK
must always be set.
If CKF_DONT_BLOCK
is not set and there is no event pending on any slot then:
CKR_FUNCTION_FAILED
is returned.
Slot Events supported:
There are no events supported by this library.
Synopsis
C_WaitForSlotEvent(
CK_FLAGS flags,
CK_SLOT_ID_PTR pSlot,
CK_VOID_PTR pReserved
);
C_GetMechanismList
This function operates as specified in PKCS#11.
See the section Mechanisms for a description of the mechanisms supported by this module.
Please note the list of mechanisms may vary at run time depending on Mode settings and other configuration values. For example the smart card slots do not support any mechanisms.
Synopsis
C_GetMechanismList(
CK_SLOT_ID slotID,
CK_MECHANISM_TYPE_PTR pMechanismList,
CK_ULONG_PTR pulCount
);
Operation in WLD Mode
When ProtectToolkit is configured to operate in WLD mode, a random slot from the HSM Token List for the provided slot ID is chosen, so as not to overload a particular device and the command is forwarded to that slot.
C_GetMechanismInfo
This function operates as specified in PKCS#11 with the following exception. Normally ProtectToolkit-C will return CKR_MECHANISM_INVALID
if the mechanism type is not recognized, however, if the EntrustReady Mode is set, the structure pointed to by pInfo is cleared and CKR_OK
is returned.
See the section Mechanisms for a description of the mechanisms supported by this module.
Synopsis
C_GetMechanismInfo(
CK_SLOT_ID slotID,
CK_MECHANISM_TYPE type,
CK_MECHANISM_INFO_PTR pInfo
);
Operation in WLD Mode
When ProtectToolkit is configured to operate in WLD mode, a random slot from the HSM Token List for the provided slot ID is chosen, so as not to overload a particular device and the command is forwarded to that slot.
C_InitToken
This function operates as specified in PKCS#11 but with these following extensions. This function is disabled if the NoClearPINs flag is set in the Mode register. Any attempt to call this function in this mode will result in a result in the CKR_ACCESS_DENIED
error being returned. The Administrator must use the CT_ResetToken
function instead.
The “protected authentication path” is not applicable to this module.
The module will detect if a session is active on the token and, if so, return CKR_SESSION_EXISTS.
If the token has been already initialized and the module is not in Entrust-ready modes then the supplied pin is checked against the current SO pin. If the pin is correct, the token is wiped and the label is set (the SO pin is not changed).
If the token is currently uninitialized, or the module is in Entrust-ready mode, the token is wiped, and the new label and SO pin are set.
The Admin token cannot be re-initialized, this function will return CKR_SLOT_ID_INVALID
if the specified slot id is the admin token.
Synopsis
C_InitToken(
CK_SLOT_ID slotID,
CK_CHAR_PTR pPin,
CK_ULONG ulPinLen,
CK_CHAR_PTR pLabel
);
Operation in WLD Mode
When ProtectToolkit is configured to operate in WLD mode, this function is not supported and will return the error CKR_FUNCTION_NOT_SUPPORTED.
CT_InitToken
This function is a SafeNet extension to PKCS#11, it allows the Administrator to initialize a new Token.
It initializes the token indicated by slotId with the SO pin (pPin and ulPinLen) and pLabel.
The session hSession, must be a session to the Admin Token of the adapter and be in RW User Mode for this function to succeed otherwise CKR_SESSION_HANDLE_INVALID
is returned.
The slotId value must refer to a valid slot where the token in the slot must be in an uninitialized state, otherwise CKR_SLOT_ID_INVALID
is returned. If the slotID is valid but the token is not present then CKR_TOKEN_NOT_PRESENT
is returned.
Synopsis
CT_InitToken(
CK_SESSION_HANDLE hSession,
CK_SLOT_ID slotID,
CK_CHAR_PTR pPin,
CK_ULONG ulPinLen,
CK_CHAR_PTR pLabel
);
Operation in WLD Mode
When ProtectToolkit is configured to operate in WLD mode, this function is not supported and will return the error CKR_FUNCTION_NOT_SUPPORTED.
CT_InitPIN
This function is a SafeNet extension to the PKCS#11 function C_InitPIN.
-
The user PIN to be initialized is specified by the
userType
parameter. -
When the module is in No Clear PINS mode, the host library protection system encrypts the sensitive material before presenting it to the adapter.
-
The session specified by
hSession
must be inCKS_RW_SO_FUNCTIONS
state. -
The function returns a
CKR_PIN_ALREADY_INITIALIZED
error if the token PIN was already initialized; that is, the SO can initialize a user PIN but cannot replace a user PIN.
Synopsis
CK_RV CT_InitPIN(
CK_SESSION_HANDLE hSession,
CK_USER_TYPE userType,
CK_CHAR_PTR pPin,
CK_ULONG ulPinLen
);
Operation in WLD Mode
When ProtectToolkit is configured to operate in WLD mode, this function is not supported and will return CKR_FUNCTION_NOT_SUPPORTED
error.
CT_ResetToken
This function is a SafeNet extension to PKCS#11, it will erase (reset) the token which the session is connected to.
The session must be in RW SO Mode for this function to succeed otherwise
CKR_USER_NOT_LOGGED_IN
is returned.
This function allows Token Security Officers to reset a Token. The module will detect if other sessions are active on the token and, if so, return CKR_SESSION_EXISTS
.
This function will erase all objects it can from the token - depending on the token type some objects will no be erased. The token is left in an initialized state where the SO pin and label are set as specified by the pPin and pLabel parameters.
Note
pPin becomes the new SO pin and need not match the old SO pin value. The session is automatically terminated by this call.
Synopsis
CT_ResetToken(
CK_SESSION_HANDLE hSession,
CK_CHAR_PTR pPin,
CK_ULONG ulPinLen,
CK_CHAR_PTR pLabel
);
Operation in WLD Mode
When ProtectToolkit is configured to operate in WLD mode, this function is not supported and returns the error CKR_FUNCTION_NOT_SUPPORTED.
C_InitPIN
This function operates as specified in PKCS#11 with the following extensions:
-
When the module is in No Clear PINS mode, the host library protection system encrypts the sensitive material before presenting it to the adapter.
-
The function returns a
CKR_PIN_ALREADY_INITIALIZED
error if the token PIN was already initialized; that is, the SO can initialize a user PIN but cannot replace a user PIN.
Synopsis
C_InitPIN(
CK_SESSION_HANDLE hSession,
CK_CHAR_PTR pPin,
CK_ULONG ulPinLen
);
Operation in WLD Mode
When ProtectToolkit is configured to operate in WLD mode, this function is not supported and will return the error CKR_FUNCTION_NOT_SUPPORTED
.
C_SetPIN
This function operates as specified in PKCS#11.
When the module is in the NoClearPINs mode the host library protection system will encrypt the sensitive material before presenting it to the adapter.
Synopsis
C_SetPIN(
CK_SESSION_HANDLE hSession,
CK_CHAR_PTR pOldPin,
CK_ULONG ulOldLen,
CK_CHAR_PTR pNewPin,
CK_ULONG ulNewLen
);
Operation in WLD Mode
When ProtectToolkit is configured to operate in WLD mode, this function is not supported and will return the error CKR_FUNCTION_NOT_SUPPORTED.